Summary

Adds support for Next.js 16 cache components by improving error detection and providing helpful error messages when auth() or currentUser() are called inside a "use cache" function.

Changes

• Add ClerkUseCacheError class with symbol marker to prevent double-wrapping of error messages
• Add isNextjsUseCacheError() helper to detect "use cache" context errors with tightened regex patterns to reduce false positives
• Add isClerkUseCacheError() helper to identify already-formatted Clerk errors
• Update buildRequestLike() to throw ClerkUseCacheError with helpful message
• Update auth() and currentUser() to check for already-formatted errors before wrapping
• Update clerkClient() to re-throw ClerkUseCacheError
• Add unit tests for error detection and handling

Problem

When a developer calls auth() or currentUser() inside a "use cache" function, they receive a cryptic error about headers() not being allowed in cache contexts.

Solution

Detect these errors and provide a helpful message with a code example showing the correct pattern:

Clerk: auth() and currentUser() cannot be called inside a "use cache" function.
These functions access `headers()` internally, which is a dynamic API not allowed in cached contexts.

To fix this, call auth() outside the cached function and pass the values you need as arguments:

  async function getCachedUser(userId: string) {
    "use cache";
    const client = await clerkClient();
    return client.users.getUser(userId);
  }

  // In your component/page:
  const { userId } = await auth();
  if (userId) {
    const user = await getCachedUser(userId);
  }

Implementation details

• Uses a custom ClerkUseCacheError class with a symbol marker to prevent double-wrapping when errors bubble through multiple catch handlers (buildRequestLike → auth → currentUser)
• Tightened regex patterns in isNextjsUseCacheError() to reduce false positives - now requires specific Next.js error patterns like "use cache" combined with headers/cookies context

Test plan

• Unit tests for ClerkUseCacheError, isClerkUseCacheError(), isNextjsUseCacheError(), and isPrerenderingBailout()
• Integration tests for cache components
• Build succeeds
• All tests pass

How to verify

Setup

1. Create or use a Next.js 16 app with cache components enabled:

   // next.config.ts
   import type { NextConfig } from 'next'
   
   const nextConfig: NextConfig = {
     cacheComponents: true, // No longer under experimental in Next.js 16
   }
   
   export default nextConfig

2. Install the PR preview package:

   npm i https://pkg.pr.new/@clerk/nextjs@7595

Test the error detection

Create a page that calls auth() inside a "use cache" function:

// app/test-cache/page.tsx
import { auth } from '@clerk/nextjs/server';

async function getCachedData() {
  "use cache";
  const { userId } = await auth(); // This should trigger our helpful error
  return { userId };
}

export default async function TestPage() {
  const data = await getCachedData();
  return <div>{JSON.stringify(data)}</div>;
}

Expected behavior

Before this PR: Cryptic Next.js error about headers() not being allowed in cache contexts

After this PR: Clear error message explaining the issue and showing the correct pattern